The jdoc mode of jedit is intended for editing multi¡font hypertext documents to be viewed with the jdoc application.
This document describes the jdoc mode available with version 3.6/3.0 of jedit.
The Format Menu
As in richtext mode, the `Format' menu is available by default. (Of course, you can change which menus are available with the Mode¡Specific Preferences panel, as with any mode.)
The jdoc Menu
The `jdoc' menu has commands for applying fonts and hypertext tags to your text. The first group of commands applies various fonts to the text. (These commands work identically to the corresponding `Level n Heading' commands, but they may be easier to access, especially if you use the keyboard shortcuts, and their names give a clearer sense of how they should be used in jdoc files.)
Make Section Title
This command creates a level 1 heading. jdoc (and also jdoc mode) looks for level 1 headings to construct the `Sections' menu, so these are the main divisions of your document.
Make Subsection Heading
Make Subsubsection Heading
These commands create level 2 and 3 headings, useful for finer structure in your document. (jdoc doesn't currently treat these differently from any other font, but may use them to generate a more detailed table of contents in the future.)
Make Overall Topic Title
This command makes a level 0 heading. There should be exactly one of these, at the very top of your document. (Nothing enforces this currently, but future versions of jdoc may use this to generate an index of documents.)
The next command doesn't affect the text at all:
Show Tags at Insert...
This command shows the text widget tags in effect at the insert point. Because these can be related to the names of anchors in your document or hypertext links, you can use this for troubleshooting or to remind yourself what the name of an anchor is.
The next group of commands are used for turning the selected text into a hypertext link or anchor:
Anchor Name...
This command prompts you for a name to give to the selected region of text. The name can then be used as an anchor, the target of a hypertext link. A default name will be provided based on the content of the selected text, but you can replace it with whatever you like.
Within the editor, text that's been marked as an anchor is displayed on a stippled background, to give you some visual indication where the anchors are in your document. Anchors are not distinguished visually in jdoc itself.
Local Cross Reference...
This command prompts you for the name of an anchor in the current document. (You need to precede the name of the anchor with a hash mark, `#'.) The editor tries to guess a likely anchor name based on the selected text, but you may need to edit it. The selected text is then turned into a hypertext link to that anchor.
Cross Reference...
This command prompts you for the name of a document to link to, in the same format you would use as an argument to jdoc on the command line. The editor tries to guess a likely document name based on the selected text, but as with `Local Cross Reference...' you may need to edit it. In the panel that prompts you for the document name, you can press the Tab key to do filename completion; this is useful if you are editing several documents in the same directory that have links to each other.
You can link to a particular anchor in another document by following the document name with a hash mark (#) and the name of the anchor within that document, as in `jstools.jdoc#Preferences'. (You can leave the trailing `.jdoc' off a document name and the link will still work, but I suggest you use full names.)
You can also use World Wide Web URL's starting with `http:' or `ftp:'; jdoc will try to use Mosaic to view these.
Incidentally, the `Local Cross Reference...' and `Cross Reference...' commands actually have identical effect; they only differ in the default links they suggest.
Man Page Reference...
This command makes a link to a UNIX manual page. It prompts you for the name of a manual page, making a guess based on the selected text. As a convenience, it also changes the selected text to typewriter font. (In some cases you may want to change this to some other font afterwards.)
Note that the actual text of the manual page is not included in the document, so the manual page will be looked up on the reader's system. You should be aware that the reader may not have the same manual pages (or any at all) available as you do, and that even if the same manual pages are available, they may describe different versions of software than they do on your system.
The Sections Menu
The `Sections' menu functions identically to the `Sections' menu in jdoc; it lets you quickly jump to a particular section in your document, or to the top or bottom of the document.
Following Links
Ordinarily, clicking on a link within jdoc mode doesn't follow the link. (It would be hard to select text in a link if clicking did follow the link.) However, you may want to try following a link in your document while you compose it, for instance to see if you spelled an anchor name correctly. You can do that by holding down the Control key while you click on the link.
Saving and Loading Files
The file format jdoc files are saved in is internally identical to that that richtext¡mode files are saved in, although richtext files don't have hypertext information in them. (The names of jdoc files should end in `.jdoc', and the names of richtext files should end in `.jrt'.) The first part of the file contains the actual text, and should be reasonably legible if you look directly at the file contents (with another editor, for example). This is followed by information about stretches of text with various styles - e.g., where all the sequences of boldface text start and end, and by information about special positions in the file, such as where the insert point is or where the last search started from. (This last information isn't normally used.)
(This format is implemented by the j:tag:archive_text_widget and j:tag:restore_text_widget procedures in the jtexttags.tcl library, which see for more information.)
Converting File Formats
You can use the editor's `Rich Save As...' command on the `Format' menu to convert your document to other formats. Currently, only font changes will be converted; underlining and colours are not preserved, and hypertext links are not kept, even if you're converting to a format like HTML that supports them. This is on my list of things to do.
